﻿// -----------------------------------------------------------------------
// <copyright file="IFileInfo.cs" company="Company">
// Company 2011
// </copyright>
// -----------------------------------------------------------------------

using System.Runtime.InteropServices;
using System.Security;
using System.Security.AccessControl;

namespace Company.IO.Interfaces
{
    /// <summary>
    /// Provides properties and instance methods for the creation, copying, deletion, moving, and opening of files, and aids in the creation of FileStream objects. This class cannot be inherited.
    /// </summary>
    [Guid("1ad496bc-04a0-41dd-a179-74cddcff1b0d")]
    public interface IFileInfo : IFileSystemInfo
    {
        /// <summary>
        /// Gets the size, in bytes, of the current file.
        /// </summary>
        long Length { [SecuritySafeCritical]
        get; }

        /// <summary>
        /// Gets a string representing the directory's full path.
        /// </summary>
        string DirectoryName { [SecuritySafeCritical]
        get; }

        /// <summary>
        /// Gets an instance of the parent directory.
        /// </summary>
        IDirectoryInfo Directory { [SecuritySafeCritical]
        get; }

        /// <summary>
        /// Gets or sets a value that determines if the current file is read only.
        /// </summary>
        bool IsReadOnly { [SecuritySafeCritical]
        get; [SecuritySafeCritical]
        set; }

        /// <summary>
        /// Gets a FileSecurity object that encapsulates the access control list (ACL) entries for the file described by the current FileInfo object.
        /// </summary>
        /// <returns>A FileSecurity object that encapsulates the access control rules for the current file.</returns>
        FileSecurity GetAccessControl();

        /// <summary>
        /// Gets a FileSecurity object that encapsulates the specified type of access control list (ACL) entries for the file described by the current FileInfo object.
        /// </summary>
        /// <param name="includeSections">One of the AccessControlSections values that specifies which group of access control entries to retrieve.</param>
        /// <returns>A FileSecurity object that encapsulates the access control rules for the current file.</returns>
        FileSecurity GetAccessControl(AccessControlSections includeSections);

        /// <summary>
        /// Applies access control list (ACL) entries described by a FileSecurity object to the file described by the current FileInfo object.
        /// </summary>
        /// <param name="fileSecurity">A FileSecurity object that describes an access control list (ACL) entry to apply to the current file.</param>
        [SecuritySafeCritical]
        void SetAccessControl(FileSecurity fileSecurity);

        /// <summary>
        /// Creates a StreamReader with UTF8 encoding that reads from an existing text file.
        /// </summary>
        /// <returns>A new StreamReader with UTF8 encoding.</returns>
        [SecuritySafeCritical]
        IStreamReader OpenText();

        /// <summary>
        /// Creates a StreamWriter that writes a new text file.
        /// </summary>
        /// <returns>A new StreamWriter.</returns>
        [SecuritySafeCritical]
        IStreamWriter CreateText();

        /// <summary>
        /// Creates a StreamWriter that appends text to the file represented by this instance of the FileInfo.
        /// </summary>
        /// <returns>A new StreamWriter.</returns>
        [SecuritySafeCritical]
        IStreamWriter AppendText();

        /// <summary>
        /// Copies an existing file to a new file, disallowing the overwriting of an existing file.
        /// </summary>
        /// <param name="destFileName">The name of the new file to copy to.</param>
        /// <returns>A new file with a fully qualified path.</returns>
        IFileInfo CopyTo(string destFileName);

        /// <summary>
        /// Copies an existing file to a new file, allowing the overwriting of an existing file.
        /// </summary>
        /// <param name="destFileName">The name of the new file to copy to.</param>
        /// <param name="overwrite">true to allow an existing file to be overwritten; otherwise, false.</param>
        /// <returns>A new file, or an overwrite of an existing file if overwrite is true. If the file exists and overwrite is false, an IOException is thrown.</returns>
        IFileInfo CopyTo(string destFileName, bool overwrite);

        /// <summary>
        /// Creates a file.
        /// </summary>
        /// <returns>A new file.</returns>
        [SecuritySafeCritical]
        IStream Create();

        /// <summary>
        /// Decrypts a file that was encrypted by the current account using the Encrypt method.
        /// </summary>
        [ComVisible(false)]
        void Decrypt();

        /// <summary>
        /// Encrypts a file so that only the account used to encrypt the file can decrypt it.
        /// </summary>
        [ComVisible(false)]
        void Encrypt();

        /// <summary>
        /// Opens a file in the specified mode.
        /// </summary>
        /// <param name="mode">A FileMode constant specifying the mode (for example, Open or Append) in which to open the file.</param>
        /// <returns>A file opened in the specified mode, with read/write access and unshared.</returns>
        [SecuritySafeCritical]
        IStream Open(FileMode mode);

        /// <summary>
        /// Opens a file in the specified mode with read, write, or read/write access.
        /// </summary>
        /// <param name="mode">A FileMode constant specifying the mode (for example, Open or Append) in which to open the file.</param>
        /// <param name="access">A FileAccess constant specifying whether to open the file with Read, Write, or ReadWrite file access.</param>
        /// <returns>A IStream object opened in the specified mode and access, and unshared.</returns>
        [SecuritySafeCritical]
        IStream Open(FileMode mode, FileAccess access);

        /// <summary>
        /// Opens a file in the specified mode with read, write, or read/write access and the specified sharing option.
        /// </summary>
        /// <param name="mode">A FileMode constant specifying the mode (for example, Open or Append) in which to open the file.</param>
        /// <param name="access">A FileAccess constant specifying whether to open the file with Read, Write, or ReadWrite file access.</param>
        /// <param name="share">A FileShare constant specifying the type of access other FileStream objects have to this file.</param>
        /// <returns>A IStream object opened with the specified mode, access, and sharing options.</returns>
        [SecuritySafeCritical]
        IStream Open(FileMode mode, FileAccess access, FileShare share);

        /// <summary>
        /// Creates a read-only IStream.
        /// </summary>
        /// <returns>A new read-only IStream object.</returns>
        [SecuritySafeCritical]
        IStream OpenRead();

        /// <summary>
        /// Creates a write-only IStream.
        /// </summary>
        /// <returns>A write-only unshared IStream object for a new or existing file.</returns>
        [SecuritySafeCritical]
        IStream OpenWrite();

        /// <summary>
        /// Moves a specified file to a new location, providing the option to specify a new file name.
        /// </summary>
        /// <param name="destFileName">The path to move the file to, which can specify a different file name.</param>
        [SecuritySafeCritical]
        void MoveTo(string destFileName);

        /// <summary>
        /// Replaces the contents of a specified file with the file described by the current FileInfo object, 
        /// deleting the original file, and creating a backup of the replaced file.
        /// </summary>
        /// <param name="destinationFileName">The name of a file to replace with the current file.</param>
        /// <param name="destinationBackupFileName">The name of a file with which to create a backup of the file described by the destFileName parameter.</param>
        /// <returns>A FileInfo object that encapsulates information about the file described by the destFileName parameter.</returns>
        [SecuritySafeCritical]
        [ComVisible(false)]
        IFileInfo Replace(string destinationFileName, string destinationBackupFileName);

        /// <summary>
        /// Replaces the contents of a specified file with the file described by the current FileInfo object, 
        /// deleting the original file, and creating a backup of the replaced file. 
        /// Also specifies whether to ignore merge errors.
        /// </summary>
        /// <param name="destinationFileName">The name of a file to replace with the current file.</param>
        /// <param name="destinationBackupFileName">The name of a file with which to create a backup of the file described by the destFileName parameter.</param>
        /// <param name="ignoreMetadataErrors">true to ignore merge errors (such as attributes and ACLs) from the replaced file to the replacement file; otherwise false.</param>
        /// <returns>A FileInfo object that encapsulates information about the file described by the destFileName parameter.</returns>
        [ComVisible(false)]
        [SecuritySafeCritical]
        IFileInfo Replace(string destinationFileName, string destinationBackupFileName, bool ignoreMetadataErrors);

        /// <summary>
        /// Returns the path as a string.
        /// </summary>
        /// <returns>A string representing the path.</returns>
        string ToString();
    }
}